home *** CD-ROM | disk | FTP | other *** search
/ Deutsche Edition 1 / Deutsche Edition 1.iso / amok / 011-020 / amok19 / trackdisksupport / trackdisksupport.doc < prev    next >
Text File  |  1993-11-04  |  11KB  |  290 lines
  1. ======================================================================
  2. Documentation for module "TrackDiskSupport" version 2.1
  3. Author: Nicolas Benezan, Postwiesenstr. 2, 7000 Stuttgart 60, Germany
  4.         Fridtjof Siebert, Nobileweg 67, D7000 Stuttgart 40
  5. Thanx to Frank Staudte for english translation
  6. ======================================================================
  7.  
  8. Copyright remarks
  9. ­­­­­­­­­­­­­­­­­
  10. (C) Copyright 1988 by Nicolas Benezan.
  11. The whole package (source, documentation and code) is donated to
  12. public domain and may be copied and redistributed providing that...
  13.  
  14. * my name and this copyright remark and
  15. * the completeness of the package remain intact,
  16. * it's distributet for non-profit only.
  17.  
  18. Commercial use without my explicit, written permission is not
  19. allowed.
  20. Furthermore, all persons working for "Data Becker" or selling
  21. products of "Data Becker" are not allowed to use this software
  22. in any way.
  23.  
  24. Improvements and new ideas are welcome, as long as the changes are
  25. well documented inline and in the documentation files. I´would like
  26. to know, if you make major changes and repost it.
  27.  
  28.  
  29. Contents
  30. ­­­­­­­­
  31. * Package info
  32. * A word by the translator
  33. * Introduction
  34. * Description of the Proedures
  35.  
  36.  
  37. Package
  38. ­­­­­­­
  39. The whole package "TrackDiskSupport" consist of following files:
  40.  
  41. * TrackDiskSupport.doc          this documentation
  42. * TrackDiskSupport.dok          german documentation
  43. * TrackDiskSupport.def, -.mod   source code
  44. * TrackDiskSupport.sym, -.obj   object code
  45. * TrackDemo.mod, -.obj          demo/test module
  46. * InhibitDemo.mod, -obj         demo/test module
  47.  
  48.  
  49.  
  50. A word by the translator
  51. ------------------------
  52. I tried to translate this documentation-file into the English without
  53. errors. At least I hope that everybody with english as his mother-tongue
  54. is able to read this without getting stomach trouble.
  55. I also had little problems with the German "Block", the German "Sektor", the
  56. English "block" and the English "sector". I hope that everything is O.K.
  57. Please refere the Rom Kernel Reference Manual Libs & Devices - chapter
  58. "TrackDiskDevice", if you have problems.
  59.  
  60. --- Frank Staudte [fst] translator
  61.  
  62.  
  63.  
  64. Introduction
  65. ------------
  66.  
  67. This Software (Version 2.1) is an improvement on the on AMOK #11 released
  68. Modul "TrackDiskSupport". It supports - like the old Version - mainly the
  69. programming of the Amiga-TrackDisk-Device". The "trackdisk.device"
  70. handles the reading and writing of single blocks and some additional
  71. funktions like turning the motor on or off or seeking around.
  72. New on this Version is that you have access to other "block-built"
  73. devices like a harddisk or some ramdisks. Also new in this Version is a
  74. function which locks a physical device for your task, so that other tasks
  75. or dos have absolutely no access to it. On the Workbench-Screen this
  76. drive is indicated as >dfx:BUSY<.
  77.  
  78.  
  79.  
  80. Description of the Procedures
  81. -----------------------------
  82.  
  83. OpenDiskDevice()
  84. ----------------
  85. Before you can start working with a Disk-Device you must open it via
  86. OpenDiskDevice(). Simply hand the Procedure the Name of the device (for
  87. example "DF0", "DH1" or "JH0") over. Be sure NOT to have a colon after
  88. the name. Names of Volumes like "Workbench" or logical devices which are
  89. assigned like "SYS" or "LIBS" are NOT allowed. Devices such as "CON", "RAW"
  90. or "PRT" which are not based on blocks are inadmissible, too. Remember that
  91. some RamDisks are bock-built (like "CARD") some are not (For Example "RAM"
  92. OR "VD0"). OpenDiskDevice() trades an an opaque Type called "DiskUnit"
  93. which is needed for further procedures (like "Seek") and an error number (0
  94. -> no error during opening!). The error number is defined in the Modul
  95. "TrackDisk", which is spread with your compiler. (only for M2Amiga-users!)
  96. They range from "notSpecified=20" to "postReset=35". Important is the error
  97. "badDriveType=33" which means, that this drive is not connected or is no
  98. block-built device (see above). Important: You can only close a device or
  99. access to it, if its opening was successful. (error = 0)
  100.  
  101. CloseDiskDevice()
  102. -----------------
  103. Please close your devices if you are finished with it. In case of an error
  104. or at the end of your program, TrackDiskSupport will close all your Drives
  105. automaticly. But don't be too lazy with it, or you might loose some of your
  106. data.
  107.  
  108.  
  109. The following procedures are allmost the same as they are implemented in
  110. "TrackDiskSupport V1.0" on AMOK #11. They handle the direkt programming
  111. of the trackdisk.devices (or other like "harddisk.device")
  112.  
  113. (...)
  114.  
  115. All procedures work with logical block numbers. which range - for example
  116. on a 3.5" disk - from 0 to 1759 (two sides, 160 tracks, 11 sectors per
  117. track). Partitions on a harddisk are handled correctly. If you want to
  118. access the first block of a hard disk partition (which starts at cylinder
  119. 100, for example), simply specify block number 0 (and not 100 x Sectors per
  120. Cylinder).
  121.  
  122. (...) (This part in the German documentation can be deleted in the
  123. English, because it handles some explanations of names, which are a
  124. little confusing for Germans, but not for English. I try to
  125. explain tracks and surfaces and so on here in English myself: Each 3.5"
  126. Floppy Disk on the Amiga has: 2 SIDES, because the Amiga has two HEADS to
  127. access the to SURFACES of the disk. A disk has 160 TRACKS (80 CYLINDERS, 2
  128. SURFACES), each TRACK contains 11 SECTORS. So there are 1760 SECTORS
  129. alltogether. Confused?)
  130.  
  131.  
  132. GetDeviceInfo()
  133. ---------------
  134. With this procedure you can get all the information about device. This
  135. information is collected in a structure (RECORD) as follows:
  136.  
  137. devName:      Name of the device (f.e. "trackdisk.device")
  138. devUnit:      Number of the drive (f.e. 2 for DF2!)
  139. devFlags      this is needed for the call of Exec.OpenDevice.
  140. blockLen:    *Size of one sector (block) in Byte
  141. trackLen:    *Size of one track in Byte
  142. cylinderLen:  Size of the cylinder in Byte
  143. numBlocks:   *Number of all sectors (blocks) on a Disk or partition of a
  144.               harddisk. All secotor-numbers must be in the range of
  145.               [0..numerBlocks-1]!
  146. offset:       Start of the harddisk-partition (internal).
  147. disk:         Pointer to some other information. (See below)
  148. handler:      The FileHandle-Process assiged to this device.
  149.  
  150. -- The following is for the multi-mega-specialists (see "DosSupport")
  151.  
  152. disk^.lenght:       Number of valid entries in the table. (usualy 11 or 16.
  153.                     ATTENTION: if "11" are all entries starting at
  154.                                BufMemType are invalid!
  155. disk^.blockSize:    LONGWORD's per sector (block)
  156. disk^.origin:       Number of the first sector (block). (always 0 (zero))
  157. disk^.surfaces:     Number of surfaces or heads.
  158. disk^.secBlock:     sectors per logical block (unused, always 1)
  159.                     (sectors and blocks are synonyms, on the Amiga)
  160. disk^.numSecs:      sectors per track
  161. disk^.resBlocks:    Number of reserved blocks (2 for the Boot-blocks)
  162. disk^.prealloc:     Preallocation-factor
  163. disk^.interleave:   Interleave-factor
  164. disk^.lowCyl:       First cylinder of the partition
  165. disk^.highCyl:      Last cylinder of the partition
  166. disk^.numBuffers:   Number of Cache-Buffers.
  167. disk^.BufMemType:   Memory attributes for cache buffers
  168. disk^.reserved1:    ???, most of the time 7FFFFFFFH
  169. disk^.reserved2:    ???, most  -2
  170. disk^.reserved3:    ???, most 0
  171. disk^.diskType:     Label of the disk. (usually "DOS")
  172.  
  173.  
  174. BlockNumber()
  175. -------------
  176. With this procedure you can calculate the logical block number simply by
  177. the cylinder surface and sector Number.
  178. IMPORTANT: Remember, that you recive the number beginning at the start of
  179.            your partition, and not at the physical start of your
  180.            harddisk.
  181.  
  182.  
  183. GetDiskChange()
  184. ---------------
  185. This procedure is equal to the "changeNum" command of the
  186. "trackdisk.device" (tdd) and returns the number of diskchanges since the
  187. system startup. Do this, if you Read or Write to your device. With this you
  188. can avoid reading/writing on a (wrong) disk, which has been changed.
  189.  
  190. ChangeState()
  191. -------------
  192. This procedure is equal to the "changeState" command of the
  193. "tdd", and returns if a disk is inserted in the device.
  194.  
  195.  
  196. ProtStatus()
  197. ------------
  198. Equal to "protStatus" in the "tdd". It returns wether you can
  199. write onto a disk or if it is write-protected.
  200.  
  201.  
  202. Motor()
  203. -------
  204. Equal to the "motor" command in the "tdd". It let's you turnig
  205. on/off the motor of a device. You need this command only for turning off
  206. the motor, because the tdd turns on the motor itself by
  207. reading or writing on the disk. Turnig off the motor on a harddisk is
  208. impossible. By doing so you move the heads of the harddisk into their
  209. "park-position", if the harddisk supportes this feature. (Try and turn on
  210. the motor of your RamDisk. Great fun, hä!)
  211.  
  212.  
  213. Seek()
  214. ------
  215. Equal to "seek" of the "tdd". You can use this to move the
  216. heads, but you don't need this. It is done by the Read/Write-Proceudres
  217. automatically. "Seek" could be used to save some time in copy programs for
  218. example.
  219.  
  220.  
  221. ReadBlock()
  222. -----------
  223. Equal to "extRead" in "tdd". Use this to read blocks of your disk. You need
  224. a blocknumber, the number of blocks to be read, and the address of a
  225. buffer. The buffer must be longword-aglined and should be in CHIP-Memory.
  226. (On other disk types test the BuffMemType. (See GetDeviceInfo). You also
  227. need the DiskChange-number (GetDiskChange), which should be stored in a
  228. variable (for multiple use).
  229.  
  230.  
  231. WriteBlock()
  232. ------------
  233. Equal to "extWrite" in "tdd". The parameters are the same as ReadBlock().
  234. So please use the above for reference.
  235.  
  236.  
  237. Update()
  238. --------
  239. Equal to "update" in "tdd". The TrackDiskDevice provides a quicker use by
  240. saving data on the disk only if the buffer for one track is full. Update
  241. stores the Buffer on disk, even if it is not compleltly full. Use this,
  242. if you do not access the disk next time, to be sure, that all data is
  243. saved. (In case of a system-crash all data in the buffer would be lost!)
  244.  
  245.  
  246. FormatTrack()
  247. -------------
  248.  
  249. Equal to "format" in TDD. It formats a track and writes data to it at the
  250. same time.
  251.  
  252.  
  253. Clear()
  254. -------
  255. Equal to "clear" in TDD. This is contrary to UpDate(). It clears the
  256. buffer and prevents it from being written to disk.
  257.  
  258.  
  259. GetDriveType() & GetNumTracks()
  260. -------------------------------
  261. This procedures are only included to be compatible to the old version of
  262. TrackDiskSupport V1.0.
  263. DO NOT USE THEM. Use "GetDeviceInfo()" instead, because some (old)
  264. harddisk-handler do not support this. This leads to some wounderfull
  265. system.crashes. (Try it, if you want)
  266.  
  267.  
  268. InhibitDrive()
  269. --------------
  270. If you need a drive for exclusive use (while copying or so), you can lock
  271. it with this procedure. FileSystem and Dos can not access to a drive which
  272. has been locked. But if somebody accesses the drive direct via Hardware,
  273. you have no chance to stop him. (Everybody doing this is to be killed. Or
  274. is supposed to programm Basic for one year!) Accessing a inhibited drive
  275. via CLI, the CLI returns a "No Dos Disk", Workbench says: "DFx:BUSY".
  276.  
  277.  
  278. IMPORTANT: The procedures to install the DiskChange-Interrupt are not
  279. ---------- implemented, because of an error in the operating-system.
  280.            They do not work!!!!!
  281.  
  282.  
  283. Demonstration/Tests:
  284. --------------------
  285. TrackDemo:   This prints information on a drive specified by its name.
  286. InhibitDemo: This locks a Drive specified by its name for 4 secs.
  287.              (DFX:Busy or DHX:Busy or JHX:Busy...)
  288. Quit the demos by typing <RETURN> without anything else.
  289.  
  290.